feat(plugin-auth): a membership that ends takes the session's claim on that organization with it — re-pointed if the user belongs elsewhere, revoked if not - #15879

Fixes #15784

Removing a member deleted the sys_member row and left the session alive, for up to seven
days. The security half was already shut per request by the ruling family's boundary card
(#15409): a session whose activeOrganizationId is not backed by a membership resolves
with no active organization. This is the courtesy half — when an admin clicks
"Remove member", that person is actually signed out.

⛔ What this is NOT

It is not the enforcement, and nothing here may be read as making the per-request check
optional. packages/core/src/security/resolve-authz-context.ts is untouched — verifiable
in one line: git diff 59953d5a3 -- packages/core/src/security/resolve-authz-context.ts is
empty. Scope item 3 stands verbatim, and the new module's header says why in the place a
future reader will be standing: a trigger can be missed, an evaluation cannot.

The census below measured a path this trigger does not cover, and it is named in the
module header rather than left to be discovered.

The census came first (scope item 1)

Posted on the card before anything was wired:
#15784 (comment)

Three readings, each with its own control, over objectstack@59953d5a3 and
cloud@3856fbf7c. Two findings shaped the implementation:

1. The dominant removal path never names the table. better-auth's ObjectQL adapter
   deletes through a variable object name (dataEngine.delete(objectName, …)), so a
   detector scanning for sys_member finds zero delete call sites in production —
   a true answer to a misleading question. The second reading enumerates the generic doors
   instead and classifies each by the abstraction it holds.
2. A raw driver delete bypasses every engine hook, and there is a real production
   caller: cloud's package-uninstall sample-data purge takes its object name from the
   installed package's manifest, ungated. Filed as cloud#2003; not fixed here.

The controls did work rather than decorate: the generic-door detector failed its own
control by over-firing on membershipCache.delete(cacheKey) and was tightened before its
numbers were used, and the runtime probe's cascade path first reported row gone=false; NOTHING because a required lookup restricted the user delete — the cascade had never run,
so it had never been measured.

Ruled shape: act on the organization's claim, never on the user

Maintainer ruling, decision batch #49 item 4, option B
(#15784 (comment)):

⛔ Option A (revoke every session of the user) and ⛔ option C (do nothing) are both
rejected on the card. The second row is the director seat's application where the option
text is silent, flagged there as flippable in one line; the measurement turned up no reason
it should be otherwise, so it is implemented as ruled.

Why the seam is an engine hook, not the endpoint

packages/plugins/plugin-auth/src/membership-ended-session.ts registers afterDelete and
afterUpdate on sys_member. The census measured which writers reach that seam:

PATH 0  engine.delete (direct)                  -> beforeDelete,afterDelete   (firing control)
PATH 1  better-auth /organization/remove-member  -> HTTP 200; row gone; beforeDelete,afterDelete
PATH 2  engine.delete multi:true                 -> beforeDelete,afterDelete
PATH 3  cascade via sys_user delete              -> row gone; beforeDelete,afterDelete
PATH 4  driver.delete (raw)                      -> row gone; NOTHING
PATH 5  engine.update re-point organization_id   -> beforeUpdate,afterUpdate

A hook on /organization/remove-member would have covered exactly one row of that table.
This is also the precedent already in the package: last-admin-guard.ts enforces its
invariant with beforeUpdate / beforeDelete on sys_member for the same stated reason.
Both new hooks are after hooks on purpose — a removal last-admin-guard refuses at
beforeDelete (priority 20) must not have its sessions touched.

The revocation reuses the existing mechanism unchanged: expires_at a second into the past
plus revoked_at / revoke_reason, the same shape enforceSessionControls and
enforceConcurrentCap already write. session-tombstone.ts already hides a revoked row
from better-auth's session reads, so findSession answers null and the Console's existing
401 to login redirect handles it. No client change.

Clause-② — the accept-set widening, re-judgeable from the diff

Yes, this widens an accept set, and the reviewer needs two facts to re-judge it:

• Where the vocabulary lives. There is no carrier in packages/spec — measured:
  grep -rn 'revoke_reason\|RevokeReason' packages/spec/src/ returns nothing. The column is
  Field.text({ maxLength: 64 }) with no Zod enum behind it, so the field description on
  the published system object IS the vocabulary, and that is the surface this PR widens
  (packages/platform-objects/src/identity/sys-session.object.ts, plus the four generated
  i18n bundles that mirror it).
• What the new value is, and why that spelling. organization_membership_ended — the
  first authorization-event reason on a column whose every prior value is a timer
  (idle_timeout, absolute_max, concurrent_cap) or an interactive revoke
  (user_revoked, admin). It is deliberately the same string the API-key arm of this
  same ruling family already mints for this event (authRefusal.reason in
  resolve-authz-context.ts, from [decision · p0] an ex-member API key reads AND writes another organization's rows on the single-kernel wiring under isolated — the wall compares against the caller's own unvetted claim #15256 decision 1A), so one grep finds every place the
  platform acts on a membership ending, across both credential kinds. 29 characters, inside
  the column's 64.

Changeset — derived from the diff, and it diverges from the ruling's literal split

The ruling said @objectstack/spec minor plus the implementing package patch,
"derive the exact set from your diff". The derivation lands elsewhere, and the divergence is
declared rather than quietly taken:

• @objectstack/spec: nothing. The diff does not touch it, because the reason
  vocabulary has no carrier there (measured above). The ruling's minor was for "the new
  reason value"; that value lives on @objectstack/platform-objects, which therefore takes
  the minor.
• @objectstack/plugin-auth: minor, not patch. It gains three public exports —
  MEMBERSHIP_ENDED_REVOKE_REASON, endSessionClaimsForEndedMembership,
  registerMembershipEndedSessionTrigger. A new export is a minor by semver; patch would
  have been right had the value lived in spec and the implementing package added no surface.

If either call should be otherwise, it is a one-line change to the changeset.

Ablation — the trigger can go red, proven on disk in both directions

Mutation: guard the registration behind a constant in auth-plugin.ts.

ABLATION_15784_DISABLED occurrences: 2   (expect 2)
unguarded registration occurrences : 0   (expect 0)
HEAD blob 2a247ce41b5a4d6b6b4ff5b7c6eea16afbcb77e1
on disk   2eb579f6e71e331543da117bac13ede29f9b4ccf
MUTATION CONFIRMED ON DISK

Rebuilt, and proven to have reached the artifact the dogfood suite actually consumes:

ablation-dist-preflight: ✓ dist/: marker present in 2 built files -- the ablation is live
                           in the artifact the suite consumes.

Ablated run — all three go red, the first on exactly the right assertion
(revoked.revoked_at, expected null to be truthy: the session survived the removal):

Test Files  1 failed (1)
     Tests  3 failed (3)

Restore leg, proven the same way rather than trusted:

whole-tree status (must be empty):   [empty]
git diff HEAD (must be empty):       [empty]
ABLATION_15784_DISABLED occurrences: 0   (expect 0)
unguarded registration occurrences : 1   (expect 1)
HEAD blob 2a247ce41b5a4d6b6b4ff5b7c6eea16afbcb77e1
on disk   2a247ce41b5a4d6b6b4ff5b7c6eea16afbcb77e1
RESTORE CONFIRMED ON DISK
ablation-dist-preflight --absent: ✓ marker absent from all 12 built files
                                  ✓ tree: working tree clean against HEAD

Acceptance and its three controls

packages/qa/dogfood/test/membership-ended-session-revoke.dogfood.test.ts — real booted
stack, real better-auth, driven through the endpoint the card names. All three controls run
in the same test as the case they control, not in a different run.

• Acceptance: removed member with no remaining membership → row tombstoned (not
  deleted), revoke_reason == organization_membership_ended, expires_at in the past, and
  GET /auth/get-session on the same token comes back unauthenticated.
• Control 1: a member of a different organization — session live, claim unchanged.
• Control 2: an intact member of the same organization — session live, claim unchanged.
• Control 3: the boundary card's pins still hold —
  packages/core/src/security/resolve-authz-context.test.ts 86 passed,
  packages/rest/src/single-kernel-isolated-session-org-claim-matrix.test.ts 13 passed,
  and the per-request check's own file is byte-identical to base.

Plus packages/plugins/plugin-auth/src/membership-ended-session.test.ts (15 tests) for the
decision table, the shapes that must be no-ops (a different organization, an already-revoked
row, an expired row, a role change), the bounded scan, and the two degradation paths.

Tests, at 61bc592f3

@objectstack/plugin-auth        Test Files  97 passed (97)   Tests  2050 passed (2050)
@objectstack/platform-objects   Test Files  33 passed (33)   Tests   518 passed (518)
@objectstack/dogfood (this file) Test Files  1 passed (1)    Tests     3 passed (3)
typecheck: plugin-auth + platform-objects — Done

Gates — 113 derived, 104 green, 9 NOT MEASURED with reasons

node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack derived its own
change set (17 paths, three-dot against merge base 59953d5a3) at 61bc592f3. Re-derived
after the docs edits, which pulled in 21 further gates the first derivation did not name,
and again after the patch round below.

Four were genuinely red and are fixed here:

The nine non-zero results, every one NOT MEASURED rather than red:

• check:partof-closing-keyword, check:single-claim-paths — exit 2, NOT WIRED: both
  need PR_BODY / PR_NUMBER. Their own words: "a wiring or usage failure, NOT a verdict".
  CI supplies the context.
• check:test-completeness, check:dual-build-cjs-loads, check:published-readme-exports,
  check:skill-examples — exit 3 / PREREQUISITE NOT MET: they read built output the
  whole-repo pnpm build produces. Each says so itself and says it is not a pass.
• check:react-declaration-parity — needs an objectui manifest and a browser dump.
• pr-labels.mjs — a usage error; the runner invoked it with no mode flag.
• check:merge-driver — pre-existing and environmental, not this change set: two
  self-test cases about "a gate whose RUNNER is not installed" fail on this host, and
  git diff 59953d5a3 -- scripts/ .gitattributes is empty, so the verdict cannot be a
  function of this diff.

Declared narrowing — verification ran UNLOCKED. scripts/pm/os-verify-lock.sh could not
take the shared verify lock on this host: no usable flock. The shared verify lock is
declared Linux-only (flock is util-linux, and a stock macOS does not ship it), so every
command above was run directly, without the lock — a declared narrowing, not a silent one.
No serialization guarantee held for these runs.

Patch round — check:i18n was red, and the miss was in my gate extraction

CI failed Type Check · consumer gates at the step running pnpm check:i18n. Reproduced
locally before acting rather than fixed on a hypothesis. The first local run answered exit
3 — PREREQUISITE NOT MET ("the workspace CLI is not built … Nothing was checked"), which
is a refusal and not a verdict; with the closure the gate names built, the real verdict was:

  platform-objects               DRIFTED (3)
check-i18n-bundles: 1 bundle problem(s)
  • platform-objects: 3 bundle(s) drifted from the schema

Cause, confirmed by measurement: the three *.source-hashes.generated.ts companions
were left stale by the field-description change — the hashes are keyed on the source
strings. pnpm i18n:extract regenerates both families in one pass and changed exactly those
three files and nothing else; the gate then reported OK (9 package(s) — all bundles in sync). Nothing was hand-edited to reach green.

The three consequence checks --fill=default demands:

Why this escaped the first round, stated plainly: the tool named the gate and my
extraction dropped it. dispatch-gates printed check:i18n under Convention-triggered
gates ("edits a file in a package that owns an i18n-extract.config.ts"), a section indented
four spaces; the regex I scraped its output with anchored on a two-space bullet and silently
lost that whole section. Five gates were dropped that way — check:i18n,
check:dispatcher-error-vocabulary, check:query-options-erasure,
check:type-check-coverage, check:type-check-debt. All five have now been run and all
five are green (check:type-check-debt needed the whole workspace built first:
12 ledger entr(ies) re-measured, 140 raw tsc error(s) total, none above its recorded number). That is the corrected 113-gate total above.

Re-verified at the patch head 61bc592f3, not at the previous one: plugin-auth 2050 tests,
platform-objects 518 tests, the dogfood acceptance file 3 tests, both typechecks Done, and
the full 113-gate union. Pushed append-only — 24536a537 is still an ancestor of the branch
head; no rebase, no force-push, no squash.

Known open, by measurement rather than omission

A raw driver delete bypasses this trigger entirely (census PATH 4), and cloud's
package-uninstall sample-data purge is one such caller — cloud#2003. The per-request
membership check covers it; the courtesy does not. That asymmetry is the whole reason this
card was filed separately from the boundary card, and it is why nothing here may be traded
against that check.

Generated by Claude Code